<!--
	$Id: readme_ru.html 19 2007-03-30 11:04:31Z beave $
-->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xml:lang="ru">
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
		<title>Parser 3. Archive. Класс для работы с архивами.</title>
		<style type="text/css">
			body {
				font-family: sans-serif;
				font-size: 70%;
			}
			h1 {
				color: green;
			}
			h2 {
				padding-top: 1em;
				border-bottom: 1px solid grey;
			}
			p.intro {
				padding-left: 50%;
				color: grey;
			}
			p.note {
				font-style: italic;
				color: brown;
			}
			pre {
				color: blue;
			}
		</style>
	</head>

	<body>
		<h1>Archive. Класс для работы с архивами.</h1>
		<p class="intro">В один день мне стало неудобно использовать ^file::cgi[...] для работы с архивами и я написал класс, помогающий мне работать с ними.</p>
		<p>Класс поддерживает архиваторы: tar (+ компрессоры: gzip и bzip2), zip и rar. Класс используется статически, т.е. нет необходимости в создании объектов с помощью конструкторов.</p>


		<!-- home directory / root path -->

		<h2>Домашний каталог и корень.</h2>
		<p>По умолчанию домашним каталогом для класса считается каталог, в котором размещен или будет размещен архив. Домашний каталог используется для работы с содержанием архива при действиях: создание и разархивирование.<br/> При указании не полного путя к файлу/каталогу на ресурсе, поиск следующего файла/каталога будет относительно домашнего каталога.</p>
		<p>&laquo;Корень&raquo; &#151; корень веб-пространства ($request:document-root).</p>
<h4>Примеры:</h4>
<p class="comment">В каталоге из которого запущен скрипт Парсера, будет создан архив, содержащий файл из этого же каталога:</p>
<pre>
^Archive:create[db_dump.zip;db_dump-${dtNow.year}${dtNow.month}${dtNow.day}.sql]
</pre>
<p class="comment">Архив, расположенный в корне, будет разархивирован в каталог texts, находящийся на 2 ступени выше относительно домашнего каталога (в данном случае он равен корню):</p>
<pre>^Archive:extract[/my_texts.rar;../../texts]</pre>


		<!-- static methods -->

		<h2>Статистические методы.</h2>
		<h3>init &#151; инициализация статистического класса</h3>
<pre>
^Archive:init[
	$.SCRIPT_PATH[путь к скрипту]
	$.DEBUG_OBJECT[объект debug-класса]
]
</pre>
		<h4>Опции:</h4>
		<p>
			<strong>$.SCRIPT_PATH[string]</strong> &#151; путь к консольному скрипту (<em>archive.sh</em> &#151; BASH / <em>archive.bat</em> &#151; MS-DOS)<br/>
			<strong>$.DEBUG_OBJECT[object]</strong> &#151; объект debug-класса, совместимый с классом Debug (P3 XML Debugger)
		</p>
		<p class="note">Примечание: при повторной инициализации класса, в случае, если не указаны какие-то опции, используются значения предыдущей инициализации, если же таковой нет, то используются значения по умолчанию.</p>

		<h3>create &#151; создание архива</h3>
<pre>
^Archive:create[имя файла;содержание]
^Archive:create[имя файла;содержание;архиватор]
^Archive:create[имя файла;содержание;архиватор;компрессор]
</pre>
		<p>
			<strong>имя файла[string]</strong> &#151; имя файла с путем<br/>
			<strong>содержание[string|table]</strong> &#151; имя архивируемого файла с путем или таблица (объект системного класса <em>table</em>) с одним столбцом <em>path</em>, содержащим архивируемые имена файлов и имена каталогов с путем (см. также &laquo;Домашний каталог и корень&raquo;)<br/>
			<strong>архиватор[string]</strong> &#151; имя архиватора<br/>
			<strong>компрессор[string]</strong> &#151; имя компрессора
		</p>
		<h3>extract &#151; разархивирование архива</h3>
<pre>
^Archive:extract[имя файла]
^Archive:extract[имя файла;путь]
^Archive:extract[имя файла;путь;архиватор]
^Archive:extract[имя файла;путь;архиватор;компрессор]
</pre>
		<p>Разархивирует архив в домашний каталог, либо в указанный каталог.</p>
		<p>
			<strong>имя файла[string]</strong> &#151; имя файла с путем<br/>
			<strong>путь[string]</strong> &#151; путь к каталогу для разархивирования (см. также &laquo;Домашний каталог и корень&raquo;)<br/>
			<strong>архиватор[string]</strong> &#151; имя архиватора<br/>
			<strong>компрессор[string]</strong> &#151; имя компрессора
		</p>
		<h3>list &#151; получение содержания архива</h3>
<pre>
^Archive:list[имя файла]
^Archive:list[имя файла;архиватор]
^Archive:list[имя файла;архиватор;компрессор]
</pre>
		<p>
			<strong>имя файла[string]</strong> &#151; имя файла с путем<br/>
			<strong>архиватор[string]</strong> &#151; имя архиватора<br/>
			<strong>компрессор[string]</strong> &#151; имя компрессора
		</p>
		<p>Формирует таблицу (объект системного класса <em>table</em>) с одним столбцом <em>path</em>, содержащим имена файлов и имена каталогов данного архива.</p>
		<p class="note">Примечание: при указании параметров &lsquo;архиватор&rsquo; и &lsquo;компрессор&rsquo;, не зависимо от того, какое расширение имеет файл, будут использованы указанные программы (поддерживаемые классом).</p>


		<!-- static fields -->

		<h2>Статистические поля.</h2>
		<h3>SCRIPT_PATH[string] &#151; получение имени файла консольного скрипта</h3>
		<h3>ARCHIVER[string] &#151; получение имени архиватора</h3>
		<h3>COMPRESSOR[string] &#151; получение имени компрессора</h3>
		<p class="note">Примечание: значения &lsquo;архиватор&rsquo; и &lsquo;компрессор&rsquo; можно получить лишь после того, как произойдет работа с архивом (создание, разархивирование и т.д.).</p>


		<!-- examples -->

		<h2>Примеры использования.</h2>
		<h3>Загрузка и разархивирование архива с другого веб-ресурса.</h3>
		<p>Предположим, нам нужен метод, который при указании ссылки на архив, находящийся на другом ресурсе, скачивал файл, сохранял его во временный каталог и разархивировал в нужный нам каталог на сервере.</p>
<pre>
@extractWebArchive[strURL;strTmpDir;strDirTo][sTmpDir;fArchive]
^if(!def $strURL){
	^throw[CLASS_NAME.spec;^$strURL;param not specified]
}

^if(def $strTmpDir){
	$sTmpDir[$strTmpDir]
}{
	$sTmpDir[/../data/tmp]
}

^if(^strURL.left(4) ne 'http'){
	^throw[CLASS_NAME.url.type;^$strURL;unknown url type]
}

$fArchive[^file::load[$strURL]]
^fArchive.save[binary;$sTmpDir]

^Archive:extract[$sTmpDir/$fArchive.name;$strDirTo]

$result[]
#end @extractWebArchive[]
</pre>
	</body>
</html>
